Skip to main content
Expert Talk
Amakomaya — Aamako Maya Apps Pvt. Ltd.

FHIR Facade

A FHIR facade is a translation layer that presents an existing system's data as FHIR resources over a standard REST API, without changing the underlying system or migrating its data.

It is the most commonly used pattern in real health integration work, because most of the data anyone wants is already in a system that cannot be replaced.

1. Problem​

A system holds clinically valuable data. It cannot be replaced — it is in production, the vendor contract runs for years, replacement would take a decade, or the source is simply outside your control. But consumers need standards-based access to that data.

2. Context​

Applies when: the source system is fixed; consumers require FHIR; and full migration is not viable on the required timescale.

3. Architecture​

   FHIR clients (apps, HIE, analytics, decision support)
              │  GET /Patient?identifier=…
              ▼
   ┌────────────────────────────────────────────┐
   │  FHIR facade                               │
   │   · parse FHIR search parameters           │
   │   · translate to the source's query model  │
   │   · map records to profiled resources      │
   │   · translate codes via terminology svc    │
   │   · enforce authorisation + audit          │
   └───────────────┬────────────────────────────┘
                   │ native query (SQL, SOAP, proprietary API)
                   ▼
   ┌────────────────────────────────────────────┐
   │  Existing system — unchanged               │
   └────────────────────────────────────────────┘

Two variants:

  • Live translation. Every FHIR request is translated and executed against the source. No duplication, always current, and the source bears the query load.
  • Materialised. Data is replicated into a FHIR server on a schedule or via change data capture. Fast and independent, but stale by the replication interval and duplicative.

Live translation is preferred where the source can bear the load, because it avoids a second copy of clinical data with its own governance obligations. Materialisation is the usual answer when the source is fragile — and many are.

4. Components​

  • Search parameter translator — FHIR search semantics to native query
  • Resource mapper — source records to profiled FHIR resources
  • Terminology translation — local codes to standard, via a terminology service, not a hard-coded table
  • Identity resolution — local identifiers to shared ones, via the client registry
  • Authorisation and audit — the facade is the security boundary; the source system generally has no concept of the caller
  • CapabilityStatement — an honest declaration of what is actually supported

5. Data flow​

 GET /Observation?patient=1234&code=http://loinc.org|2160-0&date=ge2026-01-01
        │
        ├─ resolve patient 1234 → local MRN via client registry
        ├─ translate LOINC 2160-0 → local test code via ConceptMap
        ├─ build native query
        ├─ execute against source
        ├─ map result rows → Observation resources, profiled
        ├─ attach Provenance (source system, record time)
        └─ return Bundle · write AuditEvent

Every step is a place where information is lost or invented. That is the pattern's central risk.

6. Advantages​

  • No migration, no change to the source system, no vendor negotiation
  • Consumers get a standard API immediately
  • Incremental — start with one resource type and one use case
  • Reversible; the facade can be retired when the source is eventually replaced
  • Allows a national FHIR strategy to proceed without waiting for every system to be replaced

7. Disadvantages​

  • Mapping gaps are unavoidable. The source will not hold everything the profile requires.
  • Search is limited. FHIR search is expressive; native query models frequently are not. Supporting _include, chained parameters or _sort may be impossible.
  • Performance is the source's performance, and the source was not designed for this access pattern.
  • Write is much harder than read. Most facades are read-only, and should be.
  • Semantic distortion. Forcing a source concept into a FHIR resource that does not quite fit produces data that validates and misleads.
  • Ongoing maintenance as both the source schema and the FHIR profiles evolve.

8. When to use​

  • The source system cannot be replaced within the required timescale
  • Consumers need read access to well-understood data
  • Scope can be limited to specific resource types and use cases
  • Someone will own and maintain the mapping

9. When not to use​

  • When the source cannot express what the profile requires. If the profile mandates a coded diagnosis and the source holds only free text, the facade either omits the element or fabricates a code. Omitting produces resources that fail validation; fabricating produces clinical data that is wrong. Neither is acceptable — the correct response is to narrow the profile or fix the source.
  • When writes are needed. A write facade must reconcile FHIR's model with the source's business rules, validation and workflow. This usually fails, and fails silently.
  • When the source is being replaced anyway. Build the replacement FHIR-native rather than building a facade you will throw away.
  • When nobody will maintain it. An unmaintained facade drifts from the source and becomes actively misleading.

10. Example technologies​

ApproachNotes
HAPI FHIR plain serverImplement IResourceProvider per resource type; the most common approach for a custom facade
Mediators in OpenHIMWhere a facade is also an exchange participant
Integration engine channelsMirth/NextGen Connect, Apache Camel — suits message-driven sources
Vendor FHIR modulesOpenMRS FHIR module, DHIS2 FHIR adaptors, EMR vendor APIs — a facade someone else maintains, which is preferable when available
openEHR to FHIRThe standard shape when openEHR is the internal record

Doing it honestly​

The pattern's integrity depends on truthfulness about its limits:

  1. Publish an accurate CapabilityStatement. State exactly which resources, interactions and search parameters are supported. Consumers plan against it.
  2. Document the mapping element by element, including what is not mapped and why. This document is the deliverable, as much as the code is.
  3. Use Provenance to record that data came from the source system and when it was recorded.
  4. Return dataAbsentReason rather than omitting or fabricating.
  5. Do not claim conformance to an implementation guide you cannot meet. A partial facade honestly described is useful; one described as IG-conformant when it is not will break consumers in ways that are hard to diagnose.
  6. Validate your own output against the profiles in CI. See DevSecOps.

Point 5 is where this pattern most often goes wrong organisationally. Procurement pressure produces claims of FHIR conformance that the facade cannot support, and the gap surfaces months later in someone else's integration.

References​

Last updated on